home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
X User Tools
/
X User Tools (O'Reilly and Associates)(1994).ISO
/
sun4c
/
archive
/
tcltk.z
/
tcltk
/
man
/
cat3
/
CrtMainWin.3
< prev
next >
Wrap
Text File
|
1994-09-20
|
14KB
|
331 lines
Tk_CreateMainWindow(3)Tk Library Procedures
_________________________________________________________________
NAME
Tk_CreateMainWindow, Tk_CreateWindow,
Tk_CreateWindowFromPath, Tk_DestroyWindow,
Tk_MakeWindowExist - create or delete window
SYNOPSIS
#include <tk.h>
Tk_Window
Tk_CreateMainWindow(_i_n_t_e_r_p, _s_c_r_e_e_n_N_a_m_e, _b_a_s_e_N_a_m_e, _c_l_a_s_s_N_a_m_e) |
Tk_Window
Tk_CreateWindow(_i_n_t_e_r_p, _p_a_r_e_n_t, _n_a_m_e, _t_o_p_L_e_v_S_c_r_e_e_n)
Tk_Window
Tk_CreateWindowFromPath(_i_n_t_e_r_p, _t_k_w_i_n, _p_a_t_h_N_a_m_e, _t_o_p_L_e_v_S_c_r_e_e_n)
Tk_DestroyWindow(_t_k_w_i_n)
Tk_MakeWindowExist(_t_k_w_i_n)
ARGUMENTS
Tcl_Interp *_i_n_t_e_r_p (out) Tcl interpreter to
use for error report-
ing. If no error
occurs, then *_i_n_t_e_r_p
isn't modified. For
Tk_CreateMainWindow,
this interpreter is
associated per-
manently with the
created window, and
Tk-related commands
are bound into the
interpreter.
char *_s_c_r_e_e_n_N_a_m_e (in) String name of screen
on which to create
window. Has the form
_d_i_s_p_l_a_y_N_a_m_e._s_c_r_e_e_n_N_u_m,
where _d_i_s_p_l_a_y_N_a_m_e is
the name of a display
and _s_c_r_e_e_n_N_u_m is a
screen number. If
the dot and _s_c_r_e_e_n_N_u_m
are omitted, the
screen number
defaults to 0. If
_s_c_r_e_e_n_N_a_m_e is NULL or
empty string,
Tk 1
Tk_CreateMainWindow(3)Tk Library Procedures
defaults to contents
of DISPLAY environ-
ment variable.
char *_b_a_s_e_N_a_m_e (in) Name to use for this
main window. See
below for details.
char *_c_l_a_s_s_N_a_m_e (in) Class to use for |
application and for |
main window.
Tk_Window _p_a_r_e_n_t (in) Token for the window
that is to serve as
the logical parent of
the new window.
char *_n_a_m_e (in) Name to use for this
window. Must be
unique among all
children of the same
_p_a_r_e_n_t.
char *_t_o_p_L_e_v_S_c_r_e_e_n (in) Has same format as
_s_c_r_e_e_n_N_a_m_e. If NULL,
then new window is
created as an inter-
nal window. If non-
NULL, new window is
created as a top-
level window on
screen _t_o_p_L_e_v_S_c_r_e_e_n.
If _t_o_p_L_e_v_S_c_r_e_e_n is an
empty string (``'')
then new window is
created as top-level
window of _p_a_r_e_n_t's
screen.
Tk_Window _t_k_w_i_n (in) Token for window.
char *_p_a_t_h_N_a_m_e (in) Name of new window,
specified as path
name within applica-
tion (e.g. .a.b.c).
_________________________________________________________________
DESCRIPTION
The three procedures Tk_CreateMainWindow, Tk_CreateWindow,
and Tk_CreateWindowFromPath are used to create new windows
for use in Tk-based applications. Each of the procedures
Tk 2
Tk_CreateMainWindow(3)Tk Library Procedures
returns a token that can be used to manipulate the window in
other calls to the Tk library. If the window couldn't be
created successfully, then NULL is returned and _i_n_t_e_r_p-
>_r_e_s_u_l_t is modified to hold an error message.
Tk supports three different kinds of windows: main windows,
internal windows, and top-level windows. A main window is
the outermost window corresponding to an application. Main
windows correspond to the independent units of an applica-
tion, such as a view on a file that is part of an editor, or
a clock, or a terminal emulator. A main window is created
as a child of the root window of the screen indicated by the
_s_c_r_e_e_n_N_a_m_e. Each main window, and all its descendants, are
typically associated with a single Tcl command interpreter.
An internal window is an interior window of a Tk applica-
tion, such as a scrollbar or menu bar or button. A top-
level window is one that is created as a child of a screen's
root window, rather than as an interior window, but which is
logically part of some existing main window. Examples of
top-level windows are pop-up menus and dialog boxes.
Tk_CreateMainWindow creates a new main window and associates |
its _i_n_t_e_r_p argument with that window and all its eventual |
descendants. Tk_CreateMainWindow also carries out several |
other actions to set up the new application. First, it adds |
all the Tk commands to those already defined for _i_n_t_e_r_p. |
Second, it turns the new window into a toplevel widget, |
which will cause the X window to be created and mapped as |
soon as the application goes idle. Third, |
Tk_CreateMainWindow registers _i_n_t_e_r_p so that it can be
accessed remotely by other Tk applications using the send
command and the name _b_a_s_e_N_a_m_e. Normally, _b_a_s_e_N_a_m_e consists
of the name of the application followed by a space and an
identifier for this particular main window (if such an iden-
tifier is relevant). For example, an editor named mx
displaying the file foo.c would use ``mx foo.c'' as the
basename. An application that doesn't usually have multiple
instances, such as a clock program, would just use the name
of the application, e.g. ``xclock''. If _b_a_s_e_N_a_m_e is already
in use by some other registered interpreter, then
Tk_CreateMainWindow extends _b_a_s_e_N_a_m_e with a number to pro-
duce a unique name like ``mx foo.c #2'' or ``xclock #12''.
This name is used both as the name of the window (returned
by Tk_Name) and as the registered name of the interpreter. |
Fourth, Tk_CreateMainWindow sets _c_l_a_s_s_N_a_m_e as the class of |
the application (among other things, this is used for look- |
ups in the option database), and also as the class of the |
main widget.
Either internal or top-level windows may be created by cal-
ling Tk_CreateWindow. If the _t_o_p_L_e_v_S_c_r_e_e_n argument is NULL,
then the new window will be an internal window. If
Tk 3
Tk_CreateMainWindow(3)Tk Library Procedures
_t_o_p_L_e_v_S_c_r_e_e_n is non-NULL, then the new window will be a
top-level window: _t_o_p_L_e_v_S_c_r_e_e_n indicates the name of a
screen and the new window will be created as a child of the
root window of _t_o_p_L_e_v_S_c_r_e_e_n. In either case Tk will con-
sider the new window to be the logical child of _p_a_r_e_n_t: the
new window's path name will reflect this fact, options may
be specified for the new window under this assumption, and
so on. The only difference is that new X window for a top-
level window will not be a child of _p_a_r_e_n_t's X window. For
example, a pull-down menu's _p_a_r_e_n_t would be the button-like
window used to invoke it, which would in turn be a child of
the menu bar window. A dialog box might have the
application's main window as its parent. This approach
means that all the windows of an application fall into a
hierarchical arrangement with a single logical root: the
application's main window.
Tk_CreateWindowFromPath offers an alternate way of specify-
ing new windows. In Tk_CreateWindowFromPath the new window
is specified with a token for any window in the target
application (_t_k_w_i_n), plus a path name for the new window.
It produces the same effect as Tk_CreateWindow and allows
both top-level and internal windows to be created, depending
on the value of _t_o_p_L_e_v_S_c_r_e_e_n. In calls to
Tk_CreateWindowFromPath, as in calls to Tk_CreateWindow, the
parent of the new window must exist at the time of the call,
but the new window must not already exist.
In truth, the window-creation procedures don't actually
issue the command to X to create a window. Instead, they
create a local data structure associated with the window and
defer the creation of the X window. The window will actu-
ally be created by the first call to Tk_MapWindow. Deferred
window creation allows various aspects of the window (such
as its size, background color, etc.) to be modified after
its creation without incurring any overhead in the X server.
When the window is finally mapped all of the window attri-
butes can be set while creating the window.
The value returned by a window-creation procedure is not the
X token for the window (it can't be, since X hasn't been
asked to create the window yet). Instead, it is a token for
Tk's local data structure for the window. Most of the Tk
library procedures take Tk_Window tokens, rather than X
identifiers. The actual X window identifier can be
retrieved from the local data structure using the
Tk_WindowId macro; see the manual entry for Tk_WindowId for
details.
Tk_DestroyWindow deletes a window and all the data strutures
associated with it, including any event handlers created
with Tk_CreateEventHandler. In addition, Tk_DestroyWindow
Tk 4
Tk_CreateMainWindow(3)Tk Library Procedures
will delete any children of _t_k_w_i_n recursively (where chil-
dren are defined in the Tk sense, consisting of all windows
that were created with the given window as _p_a_r_e_n_t). If
_t_k_w_i_n was created by Tk_CreateInternalWindow then event
handlers interested in destroy events are invoked immedi-
ately. If _t_k_w_i_n is a top-level or main window, then the
event handlers will be invoked later, after X has seen the
request and returned an event for it.
If a window has been created but hasn't been mapped, so no X
window exists, it is possible to force the creation of the X
window by calling Tk_MakeWindowExist. This procedure issues
the X commands to instantiate the window given by _t_k_w_i_n.
KEYWORDS
create, deferred creation, destroy, display, internal win-
dow, main window, register, screen, top-level window, window
Tk 5